Release 10.1A: OpenEdge Development:
Programming Interfaces

Client-principal objects

If you use the OpenEdge internal authentication system (see the "Authenticating OpenEdge internal user IDs and passwords" section) to authenticate and set a database connection ID, the specified database authorizes access according to this user ID. Also, by default, with auditing enabled, the database records audit events associated with this user ID. However, no other information about the user session is maintained for later review.

If you use your own external authentication system to authenticate user IDs for your application, you might still have to authenticate a database connection ID (the same or different from the Progress session ID) in order to obtain authorization to connect to a given database. The database connection ID, whatever it is, continues to be the auditing ID, for any audit events that your application generates. And, there is no information about the application user session maintained for later review, except what is associated with the database connection ID.

A client-principal object allows you to establish a client login session for a given user ID, no matter how you authenticate that ID. A client login session is a run-time construct that can be in any one of several states, indicated by the LOGIN-STATE and STATE-DETAIL attributes on the client-principal object handle. These states are controlled by methods and other attribute settings of the client-principal object handle. Such states include whether the session is logged in or out, or has been suspended, expired, or otherwise failed. Thus, the client-principal object, provides the following application features:

Maintains a run-time client login session that can be optionally recorded in an OpenEdge RDBMS and also as part of an audit trail if auditing is enabled and auditing policies for the database permit.
Contains a variety of information about the client login session, such as the user ID, a description of the authentication system (domain), a description of the login environment, the state of the login session, a unique identifier for the session, and other information, some of which are optional, depending on how you use the client-principal object.
Can be used to assert and validate a user ID against a trusted domain registry, and there by set a particular type of identity from that user ID according to the type of domain registry (database or application) and associated database option settings.
Can be exported and imported to transport a user identity between different 4GL session contexts in the same application environment.

With all of its features, the ultimate purpose of a client-principal object is to enable your application to authenticate a user ID once and set that same ID many times, in many different places, thus achieving the goal of single sign-on for your entire application.

Client-principal object attributes

The client-principal object provides several attributes that you can set for various functional and informational purposes. For example, you can set an automatic expiration time for the client-principal object (and the client login session it controls). You cannot use the resulting client-principal object to assert a user identity until you seal the object using the SEAL( ) method (see Table 2–4). Whether you set them all or not, the client-principal object attributes become read-only once you have sealed the object.

For a given client-principal object, OpenEdge sets the read-only values of several attributes on behalf of the application, according to client-principal object method calls and other actions. Table 2–2 describes these attributes, listed in general usage order. For more information how these attributes are set, see Table 2–3 and Table 2–4.

Table 2–2: Client-principal object attributes you can read-only 

This attribute...	Returns this value...
LOGIN-STATE	A CHARACTER value that represents the state of the client-principal object and any client login session started with it. The default value is "LOGOUT".
STATE-DETAIL	A CHARACTER value that provides more detailed information about the most recent setting of the LOGIN-STATE attribute. Progress also sets this to any reason parameter value that you pass to the AUTHENTICATION-FAILED( ) method.
SEAL-TIMESTAMP	A DATETIME-TZ value that represents the time when the client-principal object was sealed (client session was logged in). Progress sets this value when you call the SEAL( ) method.

Before sealing a client-principal object that you have created, you must set several OpenEdge-required attributes and several optional attributes, depending on your application requirements, as described and listed in Table 2–3 in general usage order. These settings are all application defined. Unless otherwise noted, these attributes hold CHARACTER values. All references to a “user” indicate the user associated with the user ID that this client-principal object represents.

Table 2–3: Client-principal object attributes you can set

This attribute...	Sets this value...
Required attributes
SESSION-ID	(Required) A value to uniquely identify the client login session for the user represented by the client-principal object. You must set this value before sealing the object (logging in the client session). You can set this to any value, but you might want to ensure that the value is unique in case you use it as a reference to distinguish it among multiple client login sessions. To obtain a unique value, you can use the 4GL GENERATE-UUID function (see the "Creating and managing unique object identities" section). If you want to associate the login session with a local AppServer session, you can also use the SERVER-CONNECTION-ID attribute on the SESSION system handle to obtain a value. For more information on when you might do this, see the "Managing application user IDs in n-tier applications" section.
USER-ID	(Required) The authenticated user ID of the user represented by this client-principal object. You must set this value before sealing the object (logging in the client session). Note: For validation purposes, it is up to you to ensure that the DOMAIN-NAME attribute is also set to the name of the authentication system (domain) that you actually used to authenticate this user ID.
DOMAIN-NAME	(Required) The name of the authentication system (domain) used to authenticate the user ID specified by the USER-ID attribute. This is a logical name that represents the 4GL code that handles the actual authentication of the user ID. You must set this value before sealing the object (logging in the client session). To be used for validating and setting user identities, this value must be identical to one of the following: The Name field setting for a domain entry created in a connected-database trusted domain registry using the Authentication System Domains dialog box in Data Administration (see the Data Administration online help). The domain-name parameter set for a domain entry created in the application trusted domain registry using the REGISTER-DOMAIN( ) method of the SECURITY-POLICY system handle (see the "Managing Progress session IDs" section.) Note: It is up to you to ensure that the domain name you specify actually corresponds to the authentication system that you used to authenticate the user ID.
Optional attributes
DOMAIN-DESCRIPTION	A description of the authentication system (domain) used to authenticate the user’s ID.
DOMAIN-TYPE	The type of the authentication system (domain) used to authenticate the user’s ID.
LOGIN-EXPIRATION-TIMESTAMP	A DATETIME-TZ value that specifies when the client-principal object (and any login session started with it) expires. When Progress detects that the specified time has passed, it sets the LOGIN-STATE attribute to "EXPIRED" and the client-principal object becomes unusable for validation and any started client login session for the object ends. If you do not set this value, Progress ignores it and leaves it set to the Unknown value (?).
AUDIT-EVENT-CONTEXT	When auditing is enabled, an application-defined value that is stored in the _Event-context field of each audit event record generated by a client-principal object SEAL( ), LOGOUT( ), or AUTHENTICATION-FAILED( ) method.
CLIENT-TTY	The name of the terminal display for the user’s login session.
CLIENT-WORKSTATION	The name of the host workstation on which the user is working.
LOGIN-HOST	The name of the host workstation on which the user is working.
ROLES	A comma-separated string of authentication domain roles for the user ID associated with this object.

Client-principal object methods

After you create a client principal object, you can set and read any number of application-defined properties using methods on the object handle. After all attributes and properties have been set, you can invoke additional methods to start and manage a client login session. Table 2–4 describes the methods that you can invoke on a client-principal object, listed in general usage order. For more information on managing client login sessions with these methods, see the "Managing client login sessions" section.

Table 2–4: Client-principal object methods

This method...	Provides this function...
Property set and get methods
SET-PROPERTY( property-name,               property-value )	Defines a property in the client-principal object with a name (property-name) specified by a quoted string and a value specified by a character expression (property-value). You can call this method only once for each property you define in the object.
LIST-PROPERTY-NAMES( )	Returns a comma-separated list of all application-defined properties set using the SET-PROPERTY( ) method.
GET-PROPERTY( property-name )	Given the name of an application-defined property (property-name, expressed as a quoted string), returns the value assigned to that property using the SET-PROPERTY( ) method.
Login session management methods
AUTHENTICATION-FAILED( [ reason ] )	Indicates that the user ID associated with an unsealed client-principal object cannot be authenticated. After calling this method, the client-principal object is invalidated, its attributes and properties cannot be changed, and the object cannot be sealed. Calling this method also sets the LOGIN-STATE attribute to "FAILED" and writes the value of any character expression you provide for the reason parameter to the STATE-DETAIL attribute. If auditing is enabled and auditing policies permit, the method generates an audit event record to indicate a user login failure.
SEAL( key )	Given a character expression (key), indicates that the user ID associated with an unsealed client-principal object has successfully logged into its client login session. This method also generates an optional client login session record in connected databases. Before calling this method, all of the required attributes must be set (see Table 2–3). Calling this method seals the client-principal object so you cannot set any new or existing attributes or properties for the object. It also generates a digital seal that is stored with the object in the form of a message authentication code (MAC), which is based on the value of key and the contents of the object. This seal is used to validate the client-principal object before setting user identities with it. To generate a validating seal, you must ensure that the value of key is identical to the access code/domain key of an authentication domain stored in a trusted domain registry (see the "Managing client login sessions" section). Calling this method also sets the SEAL-TIMESTAMP attribute and checks the value of the LOGIN-EXPIRATION-TIMESTAMP attribute (see Table 2–3). If the client-principal object has expired, Progress sets the LOGIN-STATE attribute to "EXPIRED". Otherwise, it sets the attribute to "LOGIN". If auditing is enabled and auditing policies permit, the method generates an audit event record, along with any optional client login session record, to indicate a valid user login. After calling this method, you can use the client-principal object to assert and validate user identities using the SET-DB-CLIENT function or the SET-CLIENT( ) method on the SECURITY-POLICY system handle.
EXPORT-PRINCIPAL( )	Converts and returns a sealed (logged in) client-principal object, including all of its attribute and property settings, as a RAW value. You can then store this value or pass it as a parameter to an AppServer session to set another client-principal object using the IMPORT-PRINCIPAL method. Thus, this method allows you to transport the user identity represented by a client-principal object from one 4GL session to another.
IMPORT-PRINCIPAL( expression )	Given a RAW expression that represents a sealed client-principal object (as output from the EXPORT-PRINCIPAL( ) method), sets a target client-principal object to the contents and state of the sealed and exported client-principal object. You can then use the new sealed client-principal object to set user identities using the SET-DB-CLIENT function or the SET-CLIENT( ) method on the SECURITY-POLICY system handle.
VALIDATE-SEAL( [ key ] )	Validates the MAC seal generated for a client-principal object by the SEAL( ) method. To call this method on a sealed client-principal object, the LOGIN-STATE attribute must be set to "LOGIN". You typically validate the seal on client-principal object after you have imported it (using the IMPORT-PRINCIPAL( ) method) from some external storage that is beyond the exclusive control of your application or whose integrity is otherwise questionable. To successfully validate the seal, you must provide the method with an access code/domain key value in one of the following ways: Pass it a parameter (key) whose value is identical to the key value used to seal the object. Ensure that the application trusted domain registry contains an entry for the authentication domain defined for the client-principal object (DOMAIN-NAME attribute) and that the entry includes an access code whose value is identical to the key value used to seal the object. (see the "Managing Progress session IDs" section.) Calling this method also checks the value of the LOGIN-EXPIRATION-TIMESTAMP attribute (see Table 2–3). If the client-principal object has expired, Progress sets the LOGIN-STATE attribute to "EXPIRED".
LOGOUT( )	Indicates that the user ID associated with a sealed client-principal object has logged out of its client login session. After calling this method, the client-principal object is invalidated, its attributes and properties cannot be changed, and the object cannot be sealed. Calling this method also sets the LOGIN-STATE attribute to "LOGOUT". If auditing is enabled and auditing policies permit, the method generates an audit event record to indicate a user logout.